---
dimensions:
  type:
    primary: reference
    detail: examples
  level: intermediate
standard_title: Endpoint
language: en
title: Endpoint
description: Authors Yeuoly, Allen. This document details the structure and implementation
  of Endpoints in Dify plugins, using the Neko Cat project as an example. It covers
  defining Endpoint groups, configuring interfaces, implementing the _invoke method,
  and handling requests and responses. The document explains the meaning and usage
  of various YAML configuration fields.
---

# Endpoint

This document uses the [Neko Cat](/plugin_dev_en/9231-extension-plugin.en.mdx) project as an example to explain the structure of Endpoints within a plugin. Endpoints are HTTP interfaces exposed by the plugin, which can be used for integration with external systems. For the complete plugin code, please refer to the [GitHub repository](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko).

### Group Definition

An `Endpoint` group is a collection of multiple `Endpoints`. When creating a new `Endpoint` within a Dify plugin, you might need to fill in the following configuration.

![](https://assets-docs.dify.ai/2024/11/763dbf86e4319591415dc5a1b6948ccb.png)

Besides the `Endpoint Name`, you can add new form items by writing the group's configuration information. After clicking save, you can see the multiple interfaces it contains, which will use the same configuration information.

![](https://assets-docs.dify.ai/2024/11/b778b7093b7df0dc80a476c65ddcbe58.png)

#### **Structure**

*   `settings` (map[string] [ProviderConfig](/plugin_dev_en/0411-general-specifications.en.mdx#providerconfig)): Endpoint configuration definition. (Note: Assuming the anchor `#providerconfig` exists in the target file).
*   `endpoints` (list[string], required): Points to the specific `endpoint` interface definitions.

```yaml
settings:
  api_key:
    type: secret-input
    required: true
    label:
      en_US: API key
      zh_Hans: API key
      ja_Jp: API key
      pt_BR: API key
    placeholder:
      en_US: Please input your API key
      zh_Hans: 请输入你的 API key
      ja_Jp: あなたの API key を入れてください
      pt_BR: Por favor, insira sua chave API
endpoints:
  - endpoints/duck.yaml
  - endpoints/neko.yaml
```

### Interface Definition

*   `path` (string): Follows the Werkzeug interface standard.
*   `method` (string): Interface method, only supports `HEAD`, `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`.
*   `extra` (object): Configuration information beyond the basic details.
    *   `python` (object)
        *   `source` (string): The source code that implements this interface.

```yaml
path: "/duck/<app_id>"
method: "GET"
extra:
  python:
    source: "endpoints/duck.py"
```

### Interface Implementation

You need to implement a subclass that inherits from `dify_plugin.Endpoint` and implement the `_invoke` method.

*   **Input Parameters**
    *   `r` (Request): The `Request` object from `werkzeug`.
    *   `values` (Mapping): Path parameters parsed from the path.
    *   `settings` (Mapping): Configuration information for this `Endpoint`.
*   **Return**
    *   A `Response` object from `werkzeug`, supports streaming responses.
    *   Directly returning a string is not supported.

Example code:

```python
import json
from typing import Mapping
from werkzeug import Request, Response
from dify_plugin import Endpoint

class Duck(Endpoint):
    def _invoke(self, r: Request, values: Mapping, settings: Mapping) -> Response:
        """
        Invokes the endpoint with the given request.
        """
        app_id = values["app_id"]

        def generator():
            yield f"{app_id} <br>"

        return Response(generator(), status=200, content_type="text/html")
```

## Notes

*   Endpoints are only instantiated when the plugin is called; they are not long-running services.
*   Pay attention to security when developing Endpoints and avoid executing dangerous operations.
*   Endpoints can be used to handle Webhook callbacks or provide interfaces for other systems to connect.

If you are learning plugin development, it is recommended to first read the [Getting Started with Plugin Development](/plugin_dev_en/0211-getting-started-dify-tool.en.mdx) and the [Developer Cheatsheet](/plugin_dev_en/0131-cheatsheet.en.mdx).

## Related Resources

*   [Basic Concepts of Plugin Development](/plugin_dev_en/0111-getting-started-dify-plugin.en.mdx) - Understand the overall architecture of plugin development.
*   [Neko Cat Example](/plugin_dev_en/9231-extension-plugin.en.mdx) - An example of extension plugin development.
*   [General Specifications Definition](/plugin_dev_en/0411-general-specifications.en.mdx) - Understand common structures like ProviderConfig.
*   [Develop a Slack Bot Plugin Example](/plugin_dev_en/0432-develop-a-slack-bot-plugin.en.mdx) - Another plugin development example.
*   [Getting Started with Plugin Development](/plugin_dev_en/0211-getting-started-dify-tool.en.mdx) - Develop a plugin from scratch.
*   [Reverse Invocation of Dify Services](/plugin_dev_en/9241-reverse-invocation-app.en.mdx) - Learn how to use the reverse invocation feature. (Note: Link updated to closest available English document)

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

<CardGroup cols="2">
    <Card
        title="Edit this page"
        icon="pen-to-square"
        href="https://github.com/alterxyz/dify-docs-plugin-dev/edit/main/plugin_dev_en/0432-endpoint.en.mdx"
    >
        Help improve our documentation by contributing directly
    </Card>
    <Card
        title="Report an issue"
        icon="github"
        href="https://github.com/alterxyz/dify-docs-plugin-dev/issues/new?title=Documentation%20Issue%3A%20endpoint&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Falterxyz%2Fdify-docs-plugin-dev%2Fblob%2Fmain%2Fplugin_dev_en%2F0432-endpoint.en.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
    >
        Found an error or have suggestions? Let us know
    </Card>
</CardGroup>
